home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 20 / Cream of the Crop 20 (Terry Blount) (1996).iso / program / n_b_v203.zip / EVENTS.TXT < prev    next >
Text File  |  1996-07-04  |  8KB  |  161 lines
  1. $if 0
  2.     ┌──────────────────────────╖                        PowerBASIC v3.20
  3.  ┌──┤          DASoft          ╟──────────────────────┬──────────────────╖
  4.  │  ├──────────────────────────╢    Copyright 1995    │ DATE: 1995-10-01 ╟─╖
  5.  │  │ FILE NAME   EVENTS  .TXT ║          by          ╘════════════════─ ║ ║
  6.  │  │                          ║  Don Schullian, Jr.                     ║ ║
  7.  │  ╘══════════════════════════╝                                         ║ ║
  8.  │ A license is hereby granted to the holder to use this source code in  ║ ║
  9.  │ any program, commercial or otherwise,  without receiving the express  ║ ║
  10.  │ permission of the copyright holder and without paying any royalties,  ║ ║
  11.  │ as long as this code is not distributed in any compilable format.     ║ ║
  12.  │  IE: source code files, PowerBASIC Unit files, and printed listings   ║ ║
  13.  ╘═╤═════════════════════════════════════════════════════════════════════╝ ║
  14.    │                ....................................                   ║
  15.    ╘═══════════════════════════════════════════════════════════════════════╝
  16. $endif
  17.  
  18. BUZZ WORDS:
  19.   Event - a rectangular area of the screen containing 1 or more Items
  20.   Item  - a rectangular area inside an Event
  21.   Hot%  - the mouse cursor is on an Item with a/the button down
  22.   Hit%  - the mouse cursor is on an Item and a/the button has been clicked
  23.   Click - a button was down and is now up (released)
  24.  
  25. Events are nothing more than visible areas of the screen that contain one,
  26. or more, mouse-sensitive boxes. If the word "box" or "window" works better
  27. for you that's just fine;  the main thing to remember is that these events
  28. are self aware.  The figure below displays 3 stacked events, one on top of
  29. another. Notice that events 2 and 3 cover some portion of the Items in the
  30. first event.
  31.  
  32. Before we get started; just a moment to make a quick explanation. All the
  33. routines for handling  events work with either text mode or graphics mode.
  34. There is one entry point explicitly for text mode ( fEventOpenT? ) and one
  35. for graphics mode  ( fEventOpenG? ).  They both do the same thing the only
  36. difference is that the  text version  accepts text style addresses and the
  37. graphics version accepts graphics style addresses.
  38.  
  39. row 1     ┌─[ EVENT 1 ]──────────────────┐
  40.           │                          ┌─[ EVENT 2 ]──────────────────┐
  41.           │  ITEM #1▄ ITEM #2▄ ITEM #│                              │
  42.           │   ▀▀▀▀▀▀▀  ▀▀▀▀▀▀▀  ▀▀▀▀▀│  ITEM #1▄ ITEM #2▄ ITEM #3▄  │
  43.           │  ITEM #4▄ ITE┌─[ EVENT 3 ]──────────────────┐  ▀▀▀▀▀▀▀  │
  44.           │   ▀▀▀▀▀▀▀  ▀▀│                              │───────────┘
  45.           └──────────────│  ITEM #1▄ ITEM #2▄ ITEM #3▄  │
  46.    fig.1                 │   ▀▀▀▀▀▀▀  ▀▀▀▀▀▀▀  ▀▀▀▀▀▀▀  │
  47.                          └──────────────────────────────┘
  48.  
  49. To make events "aware" you will dim an array for the NumberOfItems + 1
  50. by 4 for the row/column corners eg. DIM E?(1:4,NumberOfItems?). Then
  51. the coordinates of the Event are loaded into the 0th element(s):
  52.                E?(1,0) = TopRow     : E?(2,0) = LeftColumn
  53.                E?(3,0) = BottomRow  : E?(4,0) = RightColumn
  54.  
  55. Each Item within the Event is then loaded into it's respective element(s):
  56.       E?(1,1) = 3  :  E?(2,1) = 14 : E?(3,1) = 4  :  E?(4,1) = 22
  57.       E?(1,2) = 3  :  E?(2,2) = 23 : E?(3,2) = 4  :  E?(4,2) = 30
  58.       E?(1,3) = 3  :  E?(2,3) = 31 : E?(3,3) = 4  :  E?(4,3) = 39
  59.       E?(1,4) = 5  :  E?(2,4) = 14 : E?(3,4) = 6  :  E?(4,4) = 22
  60.       E?(1,5) = 5  :  E?(2,5) = 23 : E?(3,5) = 6  :  E?(4,5) = 30
  61.       E?(1,6) = 5  :  E?(2,6) = 31 : E?(3,6) = 6  :  E?(4,6) = 39
  62.                      ( Reference Event 1 above )
  63.  
  64. The array is then passed to fEventOpenT? along with the number of items in
  65. the event. What is returned is the newly created Event Number. This number
  66. can be used by the calling function to determine if a "hit" belongs to it-
  67. self or to another routine and take appropriate action.
  68.  
  69. Say What?!
  70.  
  71. Each new event can cover an existing event as shown above.  If,  lets say,
  72. Event 3 is operating and our user puts the mouse on Item #1 in Event 1 and
  73. pops the button. 2 things can happen:
  74.    1) Event 3 <REQUIRES> an answer so no action is taken on the hit in N°1
  75.    2) Event 3 is told that it is no longer required and bails out
  76.       Event 2 (which called Event 3) checks to see if the "hit" belongs to
  77.         it and determines if an answer is <REQUIRED> or not and can:
  78.           1) bail out to Event 1
  79.              Event 1 accepts the "hit" and takes appropriate action
  80.           2) stay in Event 2 until an answer is given
  81.           3) re-call Event 3
  82.  
  83. In "human" language that would be something like:
  84.   Event 1 is an editing screen full of fields
  85.   Event 2 is a menu of things to do to the data being edited
  86.   Event 3 is a help screen for the menu/editing
  87.             (Eat your heart out Billy)
  88.  
  89. The only rules that are iron-clad are:
  90.   0) If you don't call EventSetup you get 5 EventBoxes and 100 ItemBoxes
  91.   1) Events must be opened and closed in order
  92.      ie: you can't close #1 until you close #2, etc
  93.   2) Higher event numbers preceded lower event numbers when being checked
  94.      ie: FOR E% = LastEvent% TO 1 STEP -1
  95.            IF MouseHitIsInsideEventBox% THEN
  96.              FOR I% = LastItemInEvent% TO 1 STEP -1
  97.                IF AnItemWasHit% THEN
  98.                  GotOne! = -1
  99.                  EXIT FUNCTION
  100.                END IF
  101.              NEXT
  102.            END IF
  103.          NEXT
  104.   3) You must have created a FUNCTION called fGetKey%
  105.      SEE: M_SETUP.DMO for a good example
  106.  
  107. Now you've got it!
  108.  
  109.  CALL EventSetup( NumberOfEvents?, NumberOfItems?? )
  110.    Default is 5,100 which would probably be more than enough for most work
  111.    but you may call this routine to fine-tune your program or to reset all
  112.    the SHARED STATIC variables in the PBU.
  113.  
  114.  MyEvent? = fOpenEventT?( E?(1,0),  NumberOfItems? )
  115.  MyEvent? = fOpenEventG?( E??(1,0), NumberOfItems? )
  116.    If we are using our array from above then NumberOfItems? would equal 6
  117.    as it is assumed that the event box is included in the array. This way
  118.    is easier on the routines you write. MyEvent? is the current event N°.
  119.  
  120.  CALL EventClose
  121.    Just before exiting the calling routine you will close it's event.
  122.  
  123.  G% = fEventKey%( HotItem%, ExetKey$ )
  124.    HotItem% (INCOMING)  is the number of the currently "hot" item
  125.    HotItem% (RETURNING) if < 0 the new "hot" item button in "DOWN" status
  126.                         if > 0 the new "hot" item button released (CLICK)
  127.                         if = 0 a key was pressed ( no mouse action )
  128.    ExetKey$ is a list of all acceptable keys or
  129.             if NULL then any key
  130.  
  131.    RULES:  fEventKey% will not return until:
  132.              1) an acceptable key is pressed
  133.              2) the mouse is "drug" to an item other than ABS(HotItem%)
  134.              3) the button has been "clicked"
  135.  
  136.            $INCLUDE "KEYCODES.INC"
  137.            DO
  138.              G% = fEventKey%( Hit%, CHR$(027,0,013,0) )
  139.              SELECT CASE G%
  140.                CASE 0                      ' mouse action
  141.                  IF Hit% < 0 THEN             ' button down
  142.                    ELSEif Hit% > 0 THEN       ' <CLICK>
  143.                  END IF
  144.                CASE %MOUSE_DOWN               ' other Event Box is Hot
  145.                CASE %MOUSE_CLICK              ' other Event Box/Item Hit!
  146.                CASE %ENTER_key                ' <ENTER>
  147.                CASE %ESC_key                  ' <ESC>
  148.              END SELECT
  149.            LOOP
  150.  
  151.  CALL EventCLEAR
  152.    clears keyboard  : SEE ClearKeyboard
  153.    awaits until all mouse buttons are "UP"
  154.  
  155.  WhichEvent? = fEventLastBox?                      ' these 2 functions are
  156.    returns the value of the last "hit" event box   ' used by the events
  157.                                                    ' "UNDER" the last event
  158.  WhichItem?  = fEventLastItem?                     ' that bailed out to get
  159.    returns the last "hit" item of fEventLastBox?   ' the current mouse info
  160.  
  161.